Salesforce Lightning

info

For technical support, contact support@sapling.ai.

Sapling's SDK integrates with Salesforce Lightning applications, offering the simplest way to add grammar and spell checking functionality to a Lightning application.

Lightning Web Components (LWC) / Locker Service

Locker Service is a Salesforce-specific JavaScript runtime environment that does not behave completely like browser web APIs. Platform differences and Salesforce-specific JavaScript implementation details are noted here.

Shadow DOM / Shadow Root

By default, Sapling's SDK renders markup in encapsulated ShadowRoot (Shadow DOM) elements to isolate them from the parent DOM's HTML, CSS, and JavaScript. Salesforce Lightning Web Components do not support shadow DOMs, so set the flag to false on instantiation.

Sapling.init({
    ...
    shadowRoot: false,
});

Refer to: Salesforce Shadow DOM Documentation

Textarea Parent Access

When the Sapling SDK observes an HTML DOM element, it uses the element's non-static parent to position edit suggestions properly. The Lightning platform will sometimes prevent access to parent objects not owned by the Lightning Web Component. Without this, Chrome will render Sapling markup against the wrong non-static parent. A workaround is to wrap Sapling elements in a div with a non-static position:

<div style="position:relative;">
    <textarea></textarea>
</div>

The non-static element does not have to be immediate. If it's simpler, the root (accessible) element can be a non-static position.

Component Element Access

Lightning DOM elements are accessed through the template property instead of the document property.

const textareas = this.template.querySelectorAll('textarea');
textareas.forEach(ta => {
    Sapling.observe(ta);
});

Refer to: Salesforce DOM Access Documentation

HTML Element Support

info

We recommend using textarea elements instead with Sapling for best compatibility, instead of Lightning web elements such as lightning-textarea and lightning-input-field.

Sapling can work with all standard web HTML text elements: textarea, contenteditable, input. The Lightning platform also includes additional web elements like lightning-textarea and lightning-input-field. These elements encapsulate standard web text elements like textarea. The DOM elements are proxied and underlying web elements cannot be accessed.

Sapling has partial support for Lightning web elements like lightning-textarea and lightning-input-field. Issues with encapsulated Lightning components are listed below:

Scroll Events

Lightning text wrapper do not emit scroll events that other DOM scrollables normally emit. This means that Sapling markup on these components does not update when scrolled.

A workaround is to disable scrolling in these elements and wrap them in a scrollable parent (div) that Sapling can access. Another workaround is to call Sapling.checkOnce on components manually when you believe the Sapling markup needs to be refreshed, either based on DOM events, a timer, or a manually triggered button.

Positioning

Lightning text wrappers do not allow inspection of the computed vertical and horizontal positioning of the underlying textarea that is being wrapped. Things that affect the positioning include padding, margin, and label sizes. If Sapling markup is positioned incorrectly, make sure that custom padding, margin, and label sizes apply to standard classes like slds-form-element__label and slds-textarea.

A workaround is instantiating the Sapling SDK with horizontal and vertical pixel offsets to adjust for positioning issues.

Sapling.init({
    ...
    lightningCompatTop: 10,
    lightningCompatLeft: 12,
});